
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

    <title>ILeo: Leo’s IPython Bridge &#8212; Leo 6.7.2 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
    <link rel="stylesheet" type="text/css" href="_static/custom.css" />
    
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    
    <script src="_static/sidebar.js"></script>
    
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Leo’s WebSocket Server" href="leoserver.html" />
    <link rel="prev" title="Embedding Leo with the leoBridge module" href="leoBridge.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="leoserver.html" title="Leo’s WebSocket Server"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="leoBridge.html" title="Embedding Leo with the leoBridge module"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="leoandotherprograms.html" accesskey="U">Leo and Other Programs</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">ILeo: Leo’s IPython Bridge</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="ileo-leo-s-ipython-bridge">
<h1>ILeo: Leo’s IPython Bridge<a class="headerlink" href="#ileo-leo-s-ipython-bridge" title="Permalink to this heading">¶</a></h1>
<div class="contents local topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#overview" id="id1">Overview</a></p></li>
<li><p><a class="reference internal" href="#starting-ileo" id="id2">Starting ILeo</a></p></li>
<li><p><a class="reference internal" href="#running-leo-scripts-from-ipython" id="id3">Running Leo scripts from IPython</a></p></li>
<li><p><a class="reference internal" href="#running-ipython-scripts-from-leo" id="id4">Running IPython scripts from Leo</a></p></li>
<li><p><a class="reference internal" href="#ileo-as-an-ipython-notebook" id="id5">ILeo as an IPython notebook</a></p></li>
<li><p><a class="reference internal" href="#ileo-and-the-valuespace-plugin" id="id6">ILeo and the valuespace plugin</a></p></li>
<li><p><a class="reference internal" href="#acknowledgements-and-history" id="id7">Acknowledgements and history</a></p></li>
</ul>
</div>
<section id="overview">
<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this heading">¶</a></h2>
<p>Leo’s <code class="docutils literal notranslate"><span class="pre">--ipython</span></code> command-line option enables two-way communication (<strong>ILeo</strong>, the <strong>IPython bridge</strong>) between Leo and IPython: you can run Leo scripts from IPython, and IPython scripts from Leo.</p>
<p>The level of integration is much deeper than conventional integration in IDEs. Most notably, you are able to store and manipulate <em>data</em> in Leo nodes, in addition to mere program code–essentially making ILeo a hierarchical spreadsheet, albeit with non-grid view of the data. The possibilities of this are endless, and the approach can be applied in wide range of problem domains with very little actual coding.</p>
</section>
<section id="starting-ileo">
<h2><a class="toc-backref" href="#id2">Starting ILeo</a><a class="headerlink" href="#starting-ileo" title="Permalink to this heading">¶</a></h2>
<p>To run Leo’s IPython bridge:</p>
<ol class="arabic simple">
<li><p>Install IPython 4.0 and above and Jupyter.</p></li>
<li><p><a class="reference external" href="installing.html#running-leo-from-a-console-window">run Leo in a console window</a> with the <code class="docutils literal notranslate"><span class="pre">--ipython</span></code> command-line option enabled. This option starts an instance of the IPython shell in the console. Leo and IPython run simultaneously and independently. Their separate event loops do not interfere with each other. The ipython-new command launches new terminals connected to the same IPython kernel.</p></li>
</ol>
</section>
<section id="running-leo-scripts-from-ipython">
<h2><a class="toc-backref" href="#id3">Running Leo scripts from IPython</a><a class="headerlink" href="#running-leo-scripts-from-ipython" title="Permalink to this heading">¶</a></h2>
<p><em>You can run any Leo script from IPython</em>. The IPython bridge injects an object called _leo into IPython’s namespace. IPython scripts may access Leo’s c and g objects as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">c</span><span class="p">,</span><span class="n">g</span> <span class="o">=</span> <span class="n">_leo</span><span class="o">.</span><span class="n">c</span><span class="p">,</span> <span class="n">_leo</span><span class="o">.</span><span class="n">g</span>
</pre></div>
</div>
<p>This allows IPython scripts to do <em>anything</em> that a Leo script can do. Scripts run from IPython <em>immediately</em> change Leo, <em>exactly</em> as if the script were run from Leo.</p>
<p><strong>Important</strong>: the _leo object is an instance of LeoNameSpace class, defined in leo.core.leoIPython.py. This class allows IPython scripts to access multiple Leo outlines at once. See the actual code for details.</p>
<p><strong>Note</strong>: _leo.c is a property which can return None in some situations. Here is its definition:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">__get_c</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&#39;&#39;&#39;Return the designated commander, or the only open commander.&#39;&#39;&#39;</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
    <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">commander</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">commander</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">commanders_list</span><span class="p">:</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">commander</span>
    <span class="k">elif</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">commanders_list</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">commanders_list</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">return</span> <span class="kc">None</span>

<span class="k">def</span> <span class="nf">__set_c</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span><span class="n">c</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&#39;&#39;&#39;Designate the commander to be returned by the getter.&#39;&#39;&#39;</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
    <span class="k">if</span> <span class="n">c</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">commanders_list</span><span class="p">:</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">commander</span> <span class="o">=</span> <span class="n">c</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="n">g</span><span class="o">.</span><span class="n">trace</span><span class="p">(</span><span class="n">g</span><span class="o">.</span><span class="n">callers</span><span class="p">())</span>
        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>

<span class="n">c</span> <span class="o">=</span> <span class="nb">property</span><span class="p">(</span>
    <span class="n">__get_c</span><span class="p">,</span> <span class="n">__set_c</span><span class="p">,</span>
    <span class="n">doc</span> <span class="o">=</span> <span class="s2">&quot;LeoNameSpace c property&quot;</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="running-ipython-scripts-from-leo">
<h2><a class="toc-backref" href="#id4">Running IPython scripts from Leo</a><a class="headerlink" href="#running-ipython-scripts-from-leo" title="Permalink to this heading">¶</a></h2>
<p><em>You can run any IPython script from Leo</em>. Leo’s ipython-exec command executes the body text of the presently selected Leo node in the address space of the IPython shell. Such scripts <em>immediately</em> affect the IPython interpreter.</p>
<p>The IPython bridge sets several global variables <em>within Leo</em>, allowing Leo scripts <em>complete</em> access to all of IPython’s code and data:</p>
<ul class="simple">
<li><p>g.app.ipk is a <em>singleton</em> instance of the InternalIPKernel class,
defined in leoIPython.py.</p></li>
<li><p>g.app.ipk.namespace is IPython’s namespace.</p></li>
<li><p>g.app.ipk.kernelApp is an IPython IPKernelApp object.</p></li>
<li><p>g.app.ipk.kernelApp.shell is an IPython InteractiveShell object.
Depending on your installation, this may be a ZMQInteractiveShell.</p></li>
</ul>
</section>
<section id="ileo-as-an-ipython-notebook">
<h2><a class="toc-backref" href="#id5">ILeo as an IPython notebook</a><a class="headerlink" href="#ileo-as-an-ipython-notebook" title="Permalink to this heading">¶</a></h2>
<p>The IPython bridge turns Leo into another kind of <a class="reference external" href="http://projects.scipy.org/ipython/ipython/wiki/NoteBook">IPython Notebook</a>. IPython users typically use %edit to produce non-trivial functions/classes instead of entering them directly on the interactive prompt. But this is a bit clumsy. With Leo, <em>every Leo node works like an IPython %edit file</em>:</p>
<ul class="simple">
<li><p>You can execute any Leo node in IPython with ipython-exec.</p></li>
<li><p>Saving your Leo outline saves all your IPython scripts.</p></li>
<li><p>You can use Leo as always to organize all your IPython scripts.</p></li>
</ul>
</section>
<section id="ileo-and-the-valuespace-plugin">
<h2><a class="toc-backref" href="#id6">ILeo and the valuespace plugin</a><a class="headerlink" href="#ileo-and-the-valuespace-plugin" title="Permalink to this heading">¶</a></h2>
<p>Leo’s valuespace.py plugin uses the ipython namespace when the <code class="docutils literal notranslate"><span class="pre">--ipython</span></code> command line switch is in effect.</p>
<p>This plugin provides a “workbook” like way to get data from Leo document to the namespace, and do calculations based on that data. Having this data be accessible to the ipython instance makes it convenient to interact and poke around with the same data.</p>
</section>
<section id="acknowledgements-and-history">
<h2><a class="toc-backref" href="#id7">Acknowledgements and history</a><a class="headerlink" href="#acknowledgements-and-history" title="Permalink to this heading">¶</a></h2>
<p>This idea got started when I (Ville M. Vainio) saw this post by Edward Ream on IPython developer mailing list: <a class="reference external" href="http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html">http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html</a></p>
<p>I was using FreeMind as mind mapping software, and so I had an immediate use case for Leo (which, incidentally, is superior to FreeMind as mind mapper). The wheels started rolling, I got obsessed with the power of this concept (everything clicked together), and Edwards excitement paralleled mine. Everything was mind-bogglingly easy/trivial, something that is typical of all promising technologies.</p>
<p>The goal of close cooperation between Leo and IPython went from vague dream to completed reality over the span of about 10 days. The IPython bridge has continued to evolve since then.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="leo_toc.html">
              <img class="logo" src="_static/LeoLogo.svg" alt="Logo"/>
            </a></p>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="leoBridge.html"
                          title="previous chapter">Embedding Leo with the leoBridge module</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="leoserver.html"
                          title="next chapter">Leo’s WebSocket Server</a></p>
  </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>

      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="leoserver.html" title="Leo’s WebSocket Server"
             >next</a> |</li>
        <li class="right" >
          <a href="leoBridge.html" title="Embedding Leo with the leoBridge module"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="leoandotherprograms.html" >Leo and Other Programs</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">ILeo: Leo’s IPython Bridge</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 1997-2023, Edward K. Ream.
      Last updated on February 28, 2023.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
    </div>
  </body>
</html>